IRIX Base Documentation 2002 November

home *** CD-ROM | disk | FTP | other *** search

/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / ifl / iflJFIF.z / iflJFIF

Wrap

Text File | 2002-10-03 | 23.7 KB | 397 lines

iiiiffffllllJJJJFFFFIIIIFFFF((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllJJJJFFFFIIIIFFFF((((3333)))) NNNNAAAAMMMMEEEE iiiiffffllllJJJJFFFFIIIIFFFF - a JFIF formatted image file HHHHEEEEAAAADDDDEEEERRRR FFFFIIIILLLLEEEE #include <ifl/iflJFIF.h> DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN This IFL format provides support for reading and writing image files with the JFIF format, Version 4. This software is based in part on the work of the Independent JPEG Group. This format implements JPEG image compression and decompression. JPEG is intended for compressing "real-world" scenes; cartoons and other non-realistic images are not its strong suit. JPEG is lossy, meaning that the output image is not necessarily identical to the input image. Hence you must not use JPEG if you have to have identical output bits. However, on typical images of real-world scenes, very good compression levels can be obtained with no visible change, and amazingly high compression levels are possible if you can tolerate a low-quality image. For more details, see the references, or just experiment with various compression settings. JFIF implements JPEG baseline and extended-sequential compression processes. Provision is made for supporting all variants of these processes, although some uncommon parameter settings aren't implemented yet. For legal reasons, the arithmetic-coding process is not implemented. At present no provision is made for supporting the progressive, hierarchical, or lossless processes defined in the standard. This format is always of type iflUChar and can be one of three color models: iflMinBlack, iflRGB or iflCMYK. Its order is always iflInterleaved and the orientation is iflUpperLeftOrigin. Its page size is forced to be the size of the image. Hence this format is not tiled. So even if one is just reading or writing a small portion of the image, the entire image will be read or written. If you wish to have tiled JPEG compressed data use the iflTIFF format. A number of tag values are available to set/query encoding/decoding parameters with the ggggeeeettttIIIItttteeeemmmm() and sssseeeettttIIIItttteeeemmmm() methods. Normally for creating or reading images in general use, the default values of these parametrs are quite sufficient and one would not need to use these methods. While encoding, i.e. creating a JPEG file, _i_f_l_J_F_I_F_c_o_m_p_r_e_s_s_i_o_n_Q_u_a_l_i_t_y can be used to set/query the compression quality; _i_f_l_J_F_I_F_g_r_a_y_S_c_a_l_e_E_n_c_o_d_i_n_g can be used to create a monochrome JPEG file from a color input. _i_f_l_J_F_I_F_e_n_a_b_l_e_O_p_t_H_u_f_f_T_a_b can be used to enable optimization of entropy encoding parameters. Advanced users can use _i_f_l_J_F_I_F_r_e_s_t_a_r_t_I_n_t_e_r_v_a_l to emit a restart marker after a specified number of MCU rows or blocks; can use _i_f_l_J_F_I_F_s_m_o_o_t_h_i_n_g_F_a_c_t_o_r to smooth the input to eliminate dithering noise. Absolute wizards can use _i_f_l_J_F_I_F_q_T_a_b_l_e to specify their own quantization tables; _s_i_f_l_J_F_I_F_s_a_m_p_l_i_n_g_F_a_c_t_o_r_s can be used to set/get the horizontal and vertical sampling factors of the different components. The "wizard" switches are intended for experimentation with JPEG. If you don't know what you are doing, _d_o_n'_t _u_s_e _t_h_e_m. You can easily produce PPPPaaaaggggeeee 1111 iiiiffffllllJJJJFFFFIIIIFFFF((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllJJJJFFFFIIIIFFFF((((3333)))) files with worse image quality and/or poorer compression than you'll get from the default settings. Furthermore, these switches should not be used when making files intended for general use, because not all JPEG implementations will support unusual JPEG parameter settings. While decoding advanced users can use _i_f_l_J_F_I_F_b_l_o_c_k_S_m_o_o_t_h_i_n_g to perform cross block smoothing; _i_f_l_J_F_I_F_g_r_a_y_S_c_a_l_e_D_e_c_o_d_i_n_g can be used to force gray-scale output even if JPEG file is color. The environment variable JPEGMEM can be used to set the limit for amount of memory to use in processing large images. Value is in thousands of bytes, or millions of bytes if "M" is attached to the number. For example, setting JPEGMEM to 4m selects 4000000 bytes. If you get an "insufficient memory" error, try specifying a smaller memory value, even 0 to use the absolute minimum space. For most cases you would not need to set JPEGMEM. The default extension for image files in the JFIF format is '.jpg'. When you create a file with that extension IFL will assume you want the JFIF format, unless you override it with the iflFormat parameter. TTTTAAAAGGGG VVVVAAAALLLLUUUUEEEESSSS FFFFOOOORRRR GGGGEEEETTTT IIIITTTTEEEEMMMM The followng tag values are supported with ggggeeeettttIIIItttteeeemmmm(): iiiiffffllllJJJJFFFFIIIIFFFFccccoooommmmpppprrrreeeessssssssiiiioooonnnnQQQQuuuuaaaalllliiiittttyyyy iflStatus getItem(iiiiffffllllJJJJFFFFIIIIFFFFccccoooommmmpppprrrreeeessssssssiiiioooonnnnQQQQuuuuaaaalllliiiittttyyyy, int* val) This function returns the value of the quality factor used in encoding or creating the JFIF image file. The "quality factor" is the amount by which quantization tables are scaled to adjust image quality. iiiiffffllllJJJJFFFFIIIIFFFFrrrreeeessssttttaaaarrrrttttIIIInnnntttteeeerrrrvvvvaaaallll iflStatus getItem(iiiiffffllllJJJJFFFFIIIIFFFFrrrreeeessssttttaaaarrrrttttIIIInnnntttteeeerrrrvvvvaaaallll, int* val) This function returns the value of the restart interval used in encoding or creating the JFIF image file. This is the interval at which a JPEG restart marker is emitted. This interval is either in number of MCU rows or blocks. iiiiffffllllJJJJFFFFIIIIFFFFqqqqTTTTaaaabbbblllleeee iflStatus getItem(iiiiffffllllJJJJFFFFIIIIFFFFqqqqTTTTaaaabbbblllleeee, char** qtablefile) This function returns the filename from which the custom quantization tables were read. These are tables used in encoding or creating the JFIF image file. If default tables were used, NULL is returned. iiiiffffllllJJJJFFFFIIIIFFFFssssaaaammmmpppplllliiiinnnnggggFFFFaaaaccccttttoooorrrrssss PPPPaaaaggggeeee 2222 iiiiffffllllJJJJFFFFIIIIFFFF((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllJJJJFFFFIIIIFFFF((((3333)))) iflStatus getItem(iiiiffffllllJJJJFFFFIIIIFFFFssssaaaammmmpppplllliiiinnnnggggFFFFaaaaccccttttoooorrrrssss, * horiz, int* vert, int ch) The horizontal and vertical sampling factors used (in encoding or creating the JFIF image file) for channel _c_h are returned in _h_o_r_i_z and _v_e_r_t. iiiiffffllllJJJJFFFFIIIIFFFFssssmmmmooooooootttthhhhiiiinnnnggggFFFFaaaaccccttttoooorrrr iflStatus getItem(iiiiffffllllJJJJFFFFIIIIFFFFssssmmmmooooooootttthhhhiiiinnnnggggFFFFaaaaccccttttoooorrrr, int* val) This function returns the value of the smoothing factor, used to eliminate dithering noise while encoding or creating the JFIF image file. The value ranging from 0 to 100, indicates the strength of smoothing. Zero means no smoothing. iiiiffffllllJJJJFFFFIIIIFFFFbbbblllloooocccckkkkSSSSmmmmooooooootttthhhhiiiinnnngggg iflStatus getItem(iiiiffffllllJJJJFFFFIIIIFFFFbbbblllloooocccckkkkSSSSmmmmooooooootttthhhhiiiinnnngggg, int* on) This function returns TRUE if cross-block smoothing (a decoding parameter) is enabled; FALSE otherwise. iiiiffffllllJJJJFFFFIIIIFFFFggggrrrraaaayyyySSSSccccaaaalllleeeeDDDDeeeeccccooooddddiiiinnnngggg iflStatus getItem(iiiiffffllllJJJJFFFFIIIIFFFFggggrrrraaaayyyySSSSccccaaaalllleeeeDDDDeeeeccccooooddddiiiinnnngggg, int* on) This function returns TRUE if grayscale decoding is enabled i.e.a color file is read as a monochrome image; FALSE otherwise. iiiiffffllllJJJJFFFFIIIIFFFFggggrrrraaaayyyySSSSccccaaaalllleeeeEEEEnnnnccccooooddddiiiinnnngggg iflStatus getItem(iiiiffffllllJJJJFFFFIIIIFFFFggggrrrraaaayyyySSSSccccaaaalllleeeeEEEEnnnnccccooooddddiiiinnnngggg, int* on) This function returns TRUE if grayscale encoding is enabled i.e.a monochrome JFIF file is created from a color input; FALSE otherwise. iiiiffffllllJJJJFFFFIIIIFFFFeeeennnnaaaabbbblllleeeeOOOOppppttttHHHHuuuuffffffffTTTTaaaabbbb iflStatus getItem(iiiiffffllllJJJJFFFFIIIIFFFFeeeennnnaaaabbbblllleeeeOOOOppppttttHHHHuuuuffffffffTTTTaaaabbbb, int* on) This function returns TRUE if optimization of entropy encoding parameters is enabled; FALSE otherwise. TTTTAAAAGGGG VVVVAAAALLLLUUUUEEEESSSS FFFFOOOORRRR SSSSEEEETTTT IIIITTTTEEEEMMMM The followng tag values are supported with sssseeeettttIIIItttteeeemmmm(): iiiiffffllllJJJJFFFFIIIIFFFFbbbblllloooocccckkkkSSSSmmmmooooooootttthhhhiiiinnnngggg iflStatus setItem(iiiiffffllllJJJJFFFFIIIIFFFFbbbblllloooocccckkkkSSSSmmmmooooooootttthhhhiiiinnnngggg, int on) PPPPaaaaggggeeee 3333 iiiiffffllllJJJJFFFFIIIIFFFF((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllJJJJFFFFIIIIFFFF((((3333)))) This function can be used to enable cross-block smoothing while decoding or reading a JFIF image file, by setting _o_n = TRUE. This is quite memory-intensive and only seems to improve the image at very low quality settings (compression quality of 10 to 20 or so). At normal quality settings it may make things worse. By default cross-block smoothing is disabled, _o_n = FALSE. This functionality is meant for advanced users with some knowledge of JPEG. iiiiffffllllJJJJFFFFIIIIFFFFggggrrrraaaayyyySSSSccccaaaalllleeeeDDDDeeeeccccooooddddiiiinnnngggg iflStatus setItem(iiiiffffllllJJJJFFFFIIIIFFFFggggrrrraaaayyyySSSSccccaaaalllleeeeDDDDeeeeccccooooddddiiiinnnngggg, int on) This function can be used to force a JFIF color file to be read as a monochrome image (i.e. iflRGB color space is converted to iflMinBlack), by setting _o_n = TRUE. iiiiffffllllJJJJFFFFIIIIFFFFggggrrrraaaayyyySSSSccccaaaalllleeeeEEEEnnnnccccooooddddiiiinnnngggg iflStatus setItem(iiiiffffllllJJJJFFFFIIIIFFFFggggrrrraaaayyyySSSSccccaaaalllleeeeEEEEnnnnccccooooddddiiiinnnngggg, int on) This method can be used to enable creation of a monochrome JFIF image file from a color (ilRGB) input, by setting _o_n = TRUE. By default this functionality is disabled and a color input produces a color output. This functionality is meant for advanced users with some knowledge of JPEG. iiiiffffllllJJJJFFFFIIIIFFFFeeeennnnaaaabbbblllleeeeOOOOppppttttHHHHuuuuffffffffTTTTaaaabbbb iflStatus setItem(iiiiffffllllJJJJFFFFIIIIFFFFeeeennnnaaaabbbblllleeeeOOOOppppttttHHHHuuuuffffffffTTTTaaaabbbb, int on) This method can be used to enable optimization of entropy encoding parameters, used while encoding or creating a JFIF image file, by setting _o_n = TRUE. By default this optimization is not enabled and default encoding parameters are used. Enabling the optimization usually makes the JPEG file a little smaller, but the compression runs somewhat slower and needs much more memory. Image quality and speed of decompression are unaffected by enabling optimization. iiiiffffllllJJJJFFFFIIIIFFFFccccoooommmmpppprrrreeeessssssssiiiioooonnnnQQQQuuuuaaaalllliiiittttyyyy iflStatus setItem(iiiiffffllllJJJJFFFFIIIIFFFFccccoooommmmpppprrrreeeessssssssiiiioooonnnnQQQQuuuuaaaalllliiiittttyyyy, int val) This function sets the quality factor used in encoding or creating a JFIF image file to _v_a_l. _v_a_l can range from 0 (worst) to 100 (best), default is 75. The quality factor lets you trade off compressed file size against quality of the reconstructed image: the higher the quality setting, the larger the JPEG file, and the closer the output image will be to the original input. Normally you want to use the lowest quality setting (smallest file) that decompresses into something visually indistinguishable from the original image. For this purpose the quality setting should be between 50 and 95; the default of 75 is often about right. If you see defects at 75, then go up 5 or 10 counts at a time until you are happy with the output image; The optimal setting will vary PPPPaaaaggggeeee 4444 iiiiffffllllJJJJFFFFIIIIFFFF((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllJJJJFFFFIIIIFFFF((((3333)))) from one image to another. iiiiffffllllJJJJFFFFIIIIFFFFqqqqTTTTaaaabbbblllleeee iflStatus setItem(iiiiffffllllJJJJFFFFIIIIFFFFqqqqTTTTaaaabbbblllleeee, char* qtablefile) This function can be used to set the quantization tables to be used in the encoding process to those in the file _q_t_a_b_l_e_f_i_l_e. The file should contain one to four tables (64 values each) as plain text. Comments preceded by '#' may be included in the file. The tables are implicitly numbered 0,1,etc. If a non-zero quality factor is also specified, the values in the file are scaled according to a quality scaling curve. If _q_t_a_b_l_e_f_i_l_e = NULL, default tables are used. This function is meant for wizards with indepth knowledge of JPEG. iiiiffffllllJJJJFFFFIIIIFFFFrrrreeeessssttttaaaarrrrttttIIIInnnntttteeeerrrrvvvvaaaallll iflStatus setItem(iiiiffffllllJJJJFFFFIIIIFFFFrrrreeeessssttttaaaarrrrttttIIIInnnntttteeeerrrrvvvvaaaallll, int val, int inRows) This function is used to set the restart interval used in encoding or creating the JFIF image file. If _i_n_R_o_w_s = TRUE then a JPEG restart marker is emitted every _v_a_l MCU rows; else if _i_n_R_o_w_s = FALSE, a JPEG restart marker is emitted every _v_a_l MCU blocks. The restart option inserts extra markers that allow a JPEG decoder to resynchronize after a transmission error. Without restart markers, any damage to a compressed file will usually ruin the image from the point of the error to the end of the image; with restart markers, the damage is usually confined to the portion of the image up to the next restart marker. Of course, the restart markers occupy extra space. We recommend _v_a_l = 1 for images that will be transmitted across unreliable networks such as Usenet. By default no extra markers (_v_a_l = 0) are emitted. This functionality is meant for advanced users with some knowledge of JPEG. iiiiffffllllJJJJFFFFIIIIFFFFssssaaaammmmpppplllliiiinnnnggggFFFFaaaaccccttttoooorrrrssss iflStatus setItem(iiiiffffllllJJJJFFFFIIIIFFFFssssaaaammmmpppplllliiiinnnnggggFFFFaaaaccccttttoooorrrrssss, int horiz, int vert, int ch) This function can be used to set the JPEG sampling factors used in creating a JFIF image file. The horizontal and vertical sampling for channel _c_h are set to _h_o_r_i_z and _v_e_r_t. This function is meant for wizards with indepth knowledge of JPEG. iiiiffffllllJJJJFFFFIIIIFFFFssssmmmmooooooootttthhhhiiiinnnnggggFFFFaaaaccccttttoooorrrr iflStatus setItem(iiiiffffllllJJJJFFFFIIIIFFFFssssmmmmooooooootttthhhhiiiinnnnggggFFFFaaaaccccttttoooorrrr, int val) This function sets the smoothing factor, useful in eliminating dithering noise, to _v_a_l. This is used while encoding or creating a JFIF image file. _v_a_l can range from 0 to 100, indicating the strength of smooting; 0, the default means no smoothing. This smoothing option filters the input to eliminate fine-scale noise. This is often useful when converting GIF PPPPaaaaggggeeee 5555 iiiiffffllllJJJJFFFFIIIIFFFF((((3333)))) IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll iiiiffffllllJJJJFFFFIIIIFFFF((((3333)))) files to JPEG: a moderate smoothing factor of 10 to 50 gets rid of dithering patterns in the input file, resulting in a smaller JPEG file and a better-looking image. Too large a smoothing factor will visibly blur the image, however. This functionality is meant for advanced users with some knowledge of JPEG. SSSSEEEEEEEE AAAALLLLSSSSOOOO iflFile, ilFileImg The best short technical introduction to the JPEG compression algorithm is: Wallace, Gregory K. "The JPEG Still Picture Compression Standard", Communications of the ACM, April 1991 (vol. 34 no. 4), pp. 30-44. (Adjacent articles in that issue discuss MPEG motion picture compression, applications of JPEG, and related topics.) If you don't have the CACM issue handy, a PostScript file containing a revised version of the article is available at ftp.uu.net, graphics/jpeg/wallace.ps.Z. The file (actually a preprint for an article to appear in IEEE Trans. Consumer Electronics) omits the sample images that appeared in CACM, but it includes corrections and some added material. Note: the Wallace article is copyright ACM and IEEE, and it may not be used for commercial purposes. A somewhat less technical, more leisurely introduction to JPEG can be found in "The Data Compression Book" by Mark Nelson, published by M&T Books (Redwood City, CA), 1991, ISBN 1-55851-216-0. This book provides good explanations and example C code for a multitude of compression methods including JPEG. It is an excellent source if you are comfortable reading C code but don't know much about data compression in general A new textbook about JPEG is "JPEG Still Image Data Compression Standard" by William B. Pennebaker and Joan L. Mitchell, published by Van Nostrand Reinhold, 1993, ISBN 0-442-01272-1. This book includes the complete text of the ISO JPEG standards (DIS 10918-1 and draft DIS 10918-2). In the US, copies of the JPEG standard itself may be ordered from ANSI Sales at (212) 642-4900. The JPEG standard does not specify all details of an interchangeable file format. For the omitted details the "JFIF" conventions, revision 1.02 is followed. A copy of the JFIF spec is available from: Literature Department C-Cube Microsystems, Inc. 399A West Trimble Road San Jose, CA 95131 (408) 944-6300 A PostScript version of this document is available at ftp.uu.net, file graphics/jpeg/jfif.ps.Z. It can also be obtained by e-mail from the C- Cube mail server, netlib@c3.pla.ca.us. Send the message "send jfif_ps from jpeg" to the server to obtain the JFIF document; send the message "help" if you have trouble. PPPPaaaaggggeeee 6666